package com.powerunion.datacollection.report.excelreport.datasource;

import java.util.Map;

import com.powerunion.datacollection.report.excelreport.DataSource;
import com.powerunion.datacollection.report.excelreport.config.DataSourceConfig;

/**
 * 数据源接口, 数据源是报表数据来源, 生成报表数据时报表框架程序会从DataSource中检索数据.
 * @author juny
 */
public interface IDataSource extends DataSource{
    /**
     * 设置数据源配置信息。
     * @param config 数据源配置信息对象。
     * @param name 数据源名称。
     */
    public void setConfigInfo(DataSourceConfig config, String name);
    /**
     * 取得数据源名称
     * @return 返回数据源的名称
     */
    public String getName();
      
    /**
     * 取得DataSource对应的配置对象 
     * @return 返回本数据源实例对应的数据源配置对象
     */
    public DataSourceConfig getConfig();
    
    /**
     * 保存属于本dataSource的参数,传入所有参数列表.
     * 该函数搜寻传入的参数列表,并插入或替换新的参数值.
     * 2006-07-26 value改为Object为了兼容以后增加对多类型的支持。
     * @param param 本数据源对应输入参数的名称
     * @param value 参数值
     */
    public void setParameter(String param, Object value);
    
    /**
     * 取得当前数据源中参数信息
     * @return 取得当前数据源中的输入参数。
     */
    public Map getParams();
    
    /**
     * 取得对应字段类型，如果该字段没有在配置文件中定义
     * 则返回null
     * @param fieldName 字段名称
     * @return 非null 则返回字段类型值；null 该字段没有定义类型
     */
    public String getFieldType(String fieldName);
    
    /**
     * 检索数据,必须判断所有配置文件中配置的输入参数都有
     * 相应的值. 否则该函数返回失败,并抛出异常.
     * @return 返回检索数据的状态：QUERY_FAILURE，QUERY_SUCCESS
     * @throws Exception 如果数据源的输入参数无效则抛出异常。
     */
    public int queryData() throws Exception;
    
    /**
     * 取得数据源类型。
     * @return 返回当前数据源的类型。
     */
    public String getType();
    
    /**
     * 初始化数据源对象. 系统在构建一个数据源对象实例时会调用该函数，
     * 该函数设计的初衷是当在构建某些用户自定义的数据源时可能需要某些初始化操作，
     * 这是用户可以重载该函数来实现，系统保证在构建数据源实例时会调用该函数一次，
     * 来进行初始化操作。典型的是在某些需要手动管理数据库连接的应用当中，
     * 可以在该函数中获得一个连接，并在destroy函数中释放相应连接。
     * @return 
     * @throws Exception
     * @see IDataSource#destroy()
     */
    public boolean initialize() throws Exception;
    
    /**
     * 释放数据源对象。具体用法参见initialize()
     * @throws Exception
     * @see IDataSource#initialize()
     */
    public void destroy()throws Exception;
    
    /**
     * 检索数据失败.
     */
    final static int QUERY_FAILURE = -1;
    /**
     * 检索数据成功.
     */
    final static int QUERY_SUCCESS = 1;
}
